Turnbull China Bikeride/Turnbull China Bikeride - Disc 2.iso/BARNET/ARMTEX/EXTRAS/ISPELL/!Ispell/!Help

Text File | 1998-06-10 | 15KB | 419 lines

                      ------------------
                      Ispell (Release 3)
                      ------------------

            (*ispell 3.1.07 [Arc1.1] / !Ispell 1.3)



Preface
-------

Changes between successive releases of Ispell are documented in
the file `!Ispell.Documents.Changes'.

Important changes from release 1 are,

 - Clicking adjust on a word in the list of suggested corrections
   results in an immediate replacement.

Important changes from release 2 are,

 - A different method of connecting !Ispell and *ispell which
   removes the intermittent start up problem which existed before
   release 3.

 - The "Abandon" button has been replaced by an "End" button.  If
   amendments have been make to the current file you will be given
   the option to skip to the end of the file ignoring all further
   misspellings so retaining any changes that have already been made.


[
IMPORTANT NOTICE:

This version of the frontend has been patched to recognise filenames
that end in "/tex" and to use the new TeX and LaTeX filetypes. Therefore
you should report bugs to me and NOT to David Bryan. He still gets the
credit, though.

10. Jun 1998
Jakob Stoklund Olesen
<[e-mail]>
]


Contents
--------

 1 Introduction
 2 Memory requirements
 3 Simple use
   3.1 Use with the Wimp front end
   3.2 Use with the CLI
   3.3 Use with RISC OS 2
 4 More about !Ispell---issues of speed
 5 Launching Ispell from another program
 6 Documentation
 7 Lexicons and alternatives
   7.1 Base dictionaries
   7.2 Personal dictionaries
 8 Copyright and copying
 9 Bugs
10 The author



1 Introduction
--------------

Ispell, as you may know if you have used a form of Unix, is an
interactive spell checker for simple text terminals.  Ispell is of
particular use if you use TeX or LaTeX.  Not only because ispell
works directly on any file containing text, but also because it is
aware of the meta-text contained within a TeX or LaTeX file.
Thus, ispell tries to keep to a minimum queries over the spelling
of words which are part of TeX or LaTeX commands.

The Ispell package consists of two parts,

*ispell - a port of Unix `ispell' 3.1.07 to RISC OS.

!Ispell - a Wimp front end which acts as a veneer over the plain
          *ispell program, performing a similar role to xspell on
          Unix.

The English dictionary included with the binary distribution has
been constructed for the widest range of users.  It contains both
British and American spellings of many words.  However, as this
may not be to everyone's liking, section 7 below discusses the
provision and use of alternative dictionaries.



2 Memory requirements
---------------------

*ispell is, in the true Unix tradition, a greedy program when it
comes to memory.  The only compression used is prefix/suffix
compression of the base dictionary.  Ispell, as it comes with its
``medium'' sized English dictionary, will require approximately
1Mb of memory to run in.  It should be noted that this is only
required while a file is being checked, and that !Ispell just
sitting on the icon bar takes up 64Kb at most.

When used under RISC OS 3.5 or greater *ispell stores its lexicon
information in a pair of dynamic areas.  *ispell works with
Virtualise.  It doesn't work very well as access of the
information is very random.  I assume that *ispell will work with
Virtual, but now that I think to test it I am currently unable to
do so.



3 Simple use
------------

3.1 Use with the Wimp front end
-------------------------------

Double click on !Ispell.  !Ispell provides interactive help.
Start an interactive help application such as Help, and you
should have no trouble in using Ispell.

When !Ispell updates a file it renames the original file by
appending a `!' to the file's name.


3.2 Use with the CLI
--------------------

The underlying *ispell program is nearly a complete port of the
Unix original.  The only omission is regular expression look up as
RISC OS doesn't come with a plain text dictionary of words, and
providing one would only take up more disc space.  Find a suitable
CLI prompt and enter,

   ispell <filename>

The ShellCLI (the `*Commands' item on the task manager's icon bar
menu) is the most obvious place to run *ispell.  A task window
provided by Edit or VMode is not suitable.  One provided by Zap
isn't really suitable.  SmallTask works just fine.  Enter

   ispell

for more information.  Help is provided from within *ispell.

When *ispell updates a file it renames the original file by
appending a `!' to its name.


3.3 Use with RISC OS 2
----------------------

I'm afraid the !Ispell interface will only work with RISC OS 3.0
or higher.  I have not been able to test the *ispell program with
RISC OS 2, but see no reason why it should not work.  If anybody
tries it they could perhaps inform me of the outcome.



4 More about !Ispell---issues of speed
--------------------------------------

It is an unfortunate consequence of the way !Ispell works that it
is slower in operation than using *ispell from a command line.
The difference in the speed of operation is most pronounced when
checking large files with few detected potential spelling errors,
and thus little user interaction.  If you have, say, a 50Kb file
that is to be rechecked after only minor alteration, using *ispell
will result in a much quicker check.  Having said this, !Ispell
multi-tasks very ``gently''.  So if you give it a large file, you
can carry on with something else and hardly be aware that it is at
work.

If !Ispell suddenly slows down in operation, try quitting any
recently started applications and see if the speed increases.  The
problem is that !Ispell takes a big speed hit if you have other
tasks taking null polls.  This is particularly unfortunate if the
task has no work to do on the null poll.  There is a minimum of
two context switches for each line checked, and the offending task
will increase that number.  Things to note include;

  - Those using Ispell as part of a (La)TeX system should be
    aware that DVIview 0.94 becomes an offender after it has
    loaded its first DVI file.  DVIview 1.00 is free of this
    problem.  You would be to advised to upgrade from version 0.94
    any way.

  - Many communications programs, by necessity, perform work in
    the background.

  - Applications which make a large use of context sensitive
    pointer shapes often repeatedly take the null poll, this
    includes the various incarnations of Impression.

  - If you have one of those programs that give you a measure of
    processor usage, you'll probably be able to quickly deduce
    which application is slowing things down.

Also, this problem is likely to be more pronounced on the RISC PC
and A7000 with RISC OS 3 due to the way memory is handled.



5 Launching Ispell from another program
---------------------------------------

Ispell can be utilised from another program in a seamless fashion
simply by running !Ispell with the name of the file to be checked
as an argument.  Given a single argument, it will not place its
icon on the icon bar and it will immediately proceed checking of
the named file.  When checking is finished, either when the end of
the file is reached or because of a user abort, it will
immediately quit.  E.g. to check `$.Doc.tex' use,

   WimpTask <Ispell$Dir> $.Doc.tex



6 Documentation
---------------

Most of the original Ispell documentation can be found in
!Ispell.Documents.Original, only the material pertaining to use
with Emacs has been omitted.  `Ispell.tex' is a machine generated
troff to LaTeX translation of `Ispell.1X'.  If you process it just
skip passed the errors.  The GNU general public licence is an
addition---see section 8 concerning its inclusion.



7 Lexicons and alternatives
---------------------------

When checking words Ispell uses lexicons from two different files:

  1. A base dictionary.
  2. A personal dictionary.


7.1 Base dictionaries
---------------------

This distribution of Ispell comes with one base dictionary.  It
contains 32,372 English root words and is held in the file
`!Ispell.Resources.English'.  It differs slightly from the
Ispell's usual base dictionary in that it contains only a set of
primary American spellings but no ``alternative'' ones.

I have produced two further archives each containing a drop-in
alternative base dictionary which contain only British spellings.
The first is simply the base dictionary provided with this
distribution with all the American spellings removed.  If you wish
to tailor dictionaries in this manner, more information is given
below.  The second is completely different in origin.  It has been
provided by Reuben Thomas, who found it after putting in some
effort looking at sites on the Internet.  It was apparently
compiled by an Australian.  It is 50% bigger than the one in this
distribution requiring about 1.5Mb to use.  Unfortunately, it is
built from a single plain text file and so it is not readily
possible to reduce its size.  Thanks go to Reuben.  The two may be
available from the site you got this distribution as the files
`IsBritish' and `IsAltBrit' respectively, if not see section 10.

A base dictionary is a specially formatted binary file in the form
of a hash table.  Such a file is created from one or more plain
text files containing lexicon fragments.  The lexicon fragment files
provided with Ispell 3.1.07 are:

     English.0
     English.1
     English.2
     English.3
     British.0
     British.1
     British.2
     American.0
     American.1
     American.2
     Altamer.0
     Altamer.1
     Altamer.2

The higher the number of the file's suffix the less common are the
words it contains.  The English lexicons contain a core of
spellings common between both International English and American
English.  The British and American lexicons contain spellings for
the two respective countries.  The Altamer lexicon contains the
alternative American spellings mentioned above.  The dictionary
provided was built using the English, British and American files
with suffixes of 0 and 1.

All the above plain text dictionary files can be found in the
source distribution.  This is probably available from the site you
got this distribution from, and probably in an archive called
`IspellSrc', if not see section 10.  Using the programs in the
directory `!Ispell.Library', you can build a base dictionary using
any collection of these lexicon fragments and personal lexicons,
to precisely tailor the base dictionary to your requirements.
Using all the above fragments results in a dictionary with 85,723
root words which requires 3Mb to build and 2Mb to use!

Which base dictionary is used can be changed from the !Ispell
`Choices' window.  If you just give the leaf name of the file it
will be looked for first in the directory !Ispell.Resources, then
in the current working directory, then finally in the user's root
directory.


7.2 Personal dictionaries
-------------------------

A personal dictionary is simply a plain text file of words, one per
line, and so can be created and managed with a text editor.  The
name of the default personal dictionary is a concatenation of
`!I_' and the name of the base dictionary.  So, as !Ispell comes,
this will be `!I_English'.  This will be looked for in the current
working directory, then the user root directory.  If no personal
dictionary can be found and words are learnt, a new personal
dictionary is created in the user's root directory.  The personal
dictionary used can be changed from the !Ispell `Choices' window.



8 Copyright and copying
-----------------------

Entering

  ispell -v

at the CLI gives as part of the output,

``Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions
  are met:

  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above
     copyright notice, this list of conditions and the following
     disclaimer in the documentation and/or other materials provided
     with the distribution.
  3. All modfications to the source code must be clearly marked as
     such.  Binary redistributions based on modified source code
     must be clearly marked as modified versions in the documentation
     and/or other materials provided with the distribution.
  4. All advertising materials mentioning features or use of this
     software must display the following acknowledgment:
       This product includes software developed by Geoff Kuenning and
       other unpaid contributors.
  5. The name of Geoff Kuenning may not be used to endorse or promote
     products derived from this software without specific prior
     written permission.

  THIS SOFTWARE IS PROVIDED BY GEOFF KUENNING AND CONTRIBUTORS ``AS
  IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL GEOFF
  KUENNING OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  OF THE POSSIBILITY OF SUCH DAMAGE.''

This notice covers only *ispell.  !Ispell is distributed under the
GNU general public licence, a copy of which can be found as
!Ispell.Documents.GNU.  May I stress clause 2a of the terms and
conditions, and point out that I will not be prepared to deal with
any problems arising from the use of copies of either *ispell or
!Ispell that contain third party alterations.  The uncompressed
form of !Ispell.!RunImage can be found in the source distribution.
This is probably available from the site you got this distribution
from, and probably in an archive called `IspellSrc', if not see
section 10.


9 Bugs
------

Unlike release 1 or 2, this release is bug free and I am a banana.



10 The author
-------------

If you have any comments, suggestions, or especially if you come
across any insurmountable problems with Ispell, then I would like
to hear from you.  You can contact me at the address below.

If you cannot obtain any of the archives described in this file
then I can provided you with the latest complete set.  Send,

  1. A stamped addressed envelope.

  2. Either
        2 high density or
        3 low density
     pre-formatted ADFS discs.

  3. A covering letter saying that you want a copy of Ispell.
     The letter can be on one of the discs if you like.

to the address below.


David Bryan
37 Mill Dale Road
Kettering
Northants
NN15 6QD
England